---
title: Comandos da Interface de Linha de Comando
i18nReady: true
---
import Since from '~/components/Since.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'



Você pode utilizar a Interface de Linha de Comando (CLI) providenciada pelo Astro para desenvolver, fazer build e pré-visualizar seu projeto a partir de uma janela de terminal.

### Comandos `astro`

Use a CLI ao executar um dos **comandos** documentados nessa página com seu gerenciador de pacotes preferido, opcionalmente seguido de algumas **flags**. Flags customizam o comportamento de um comando.

Um dos comandos que você vai usar com mais frequência é `astro dev`. Esse comando inicia o servidor de desenvolvimento e dá a você uma pré-visualização ao vivo e atualizada do seu site em um navegador conforme você trabalha:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # inicia o servidor de desenvolvimento
  npx astro dev
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # inicia o servidor de desenvolvimento
  pnpm astro dev
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # inicia o servidor de desenvolvimento
  yarn astro dev
  ```
  </Fragment>
</PackageManagerTabs>

Você pode digitar `astro --help` no seu terminal para exibir uma lista de todos os comandos disponíveis:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npx astro --help
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm astro --help
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn astro --help
  ```
  </Fragment>
</PackageManagerTabs>

A seguinte mensagem vai aparecer no seu terminal:

```bash
astro [comando] [...flags]

Comandos
                     add  Adiciona uma integração.
                   build  Faz build do seu projeto e escreve ele no disco.
                   check  Checa seu projeto por erros.
                     dev  Inicia o servidor de desenvolvimento.
                    docs  Abre a documentação no seu navegador da web.
                    info  Lista de informações sobre sua configuração atual do Astro.
                 preview  Pré-visualiza sua build localmente.
                    sync  Gera tipos de coleção de conteúdo.
               telemetry  Configura opções de telemetria.

Flags Globais
      --config <caminho>  Especifica seu arquivo de configuração.
        --root <caminho>  Especifica a pasta raiz do seu projeto.
            --site <url>  Especifica o site do seu projeto.
--base <nome-do-caminho>  Especifica a base do seu projeto.
               --verbose  Habilita o registro detalhado.
                --silent  Desabilita todos registros.
               --version  Mostra o número da versão e sai.
                  --open  Abre o aplicativo no navegador quando o servidor iniciar.
                  --help  Mostra essa mensagem de ajuda.
```

### Scripts `package.json`

Você também pode usar scripts no `package.json` para versões mais curtas desses comandos. Usando um script permite você usar os mesmos comandos que você pode estar familiarizado com outros projetos, como o `npm run build`.

Os seguintes scripts para os comandos `astro` comuns (`astro dev`, `astro build` e `astro preview`) são adicionados pra você automaticamente quando você cria um projeto usando [o assistente `create astro`](/pt-br/install/auto/#1-execute-o-assistente-de-instalação).

Quando você segue as instruções para [instalar o Astro manualmente](/pt-br/install/manual/#2-instale-astro), você é instruído a adicionar esses scripts você mesmo. Você também pode adicionar mais scripts para essa lista manualmente para qualquer comando que você usa frequentemente.

```json title="package.json"
{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}
```

Você vai frequentemente usar esses comandos `astro` ou scripts que executam eles, sem nenhuma flag. Adicione flags para o comando quando você quer customizar o comportamento do comando. Por exemplo, você pode querer iniciar o servidor de desenvolvimento em uma porta diferente ou fazer a build do seu site com registros verbosos para depuração.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # executa o servidor de desenvolvimento na porta 8080 usando o script `start` no `package.json`
  npm run start -- --port 8080

  # faz build do seu site com registros verbosos usando o script `build` script no `package.json`
  npm run build -- --verbose
  ```
  (O `--` a mais antes da flag `--port` é necessário para o `npm` passar suas flags para o comando `astro`.)
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # executa o servidor de desenvolvimento na porta 8080 usando o script `start` no `package.json`
  pnpm start --port 8080

  # faz build do seu site com registros verbosos usando o script `build` script no `package.json`
  pnpm build --verbose
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # executa o servidor de desenvolvimento na porta 8080 usando o script `start` no `package.json`
  yarn start --port 8080

  # faz build do seu site com registros verbosos usando o script `build` script no `package.json`
  yarn build --verbose
  ```
  </Fragment>
</PackageManagerTabs>

{/*

CONTEÚDO ORIGINAL Que Nós Podemos Sempre reverter se as coisas novas são muito amigáveis

Você pode utilizar a interface de linha de comando (CLI) oferecida pelo Astro para desenvolver, fazer build e visualizar seu projeto a partir de uma janela de terminal.

Use a CLI ao executar um dos **comandos** documentados nessa página, opcionalmente seguido de algumas **flags**. Flags customizam o comportamento de um comando. Por exemplo, para iniciar o servidor de desenvolvimento na porta `8080`, você combinaria o comando `astro dev` com a flag `--port`: `astro dev --port 8080`.

Na maioria dos casos você usará a CLI pelo seu gerenciador de pacotes:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npx astro dev --port 8080
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm astro dev --port 8080
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn astro dev --port 8080
  ```
  </Fragment>
</PackageManagerTabs>

Se você iniciou seu projeto utilizando [o assistente `create astro`](/pt-br/install/auto/#1-execute-o-assistente-de-instalação), você pode também utilizar os scripts em `package.json` para uma versão mais curta desses comandos. Veja o `README.md` no seu projeto para detalhes sobre quais comandos estão disponíveis.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # executa o servidor de desenvolvimento na porta 8080 utilizando o script `start` em `package.json`
  npm run start -- --port 8080
  ```
  (Os `--` adicionais antes da flag `--port` são necessários para o `npm` passar suas flags para o comando `astro`.)
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # executa o servidor de desenvolvimento na porta 8080 utilizando o script `start` em `package.json`
  pnpm start --port 8080
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # executa o servidor de desenvolvimento na porta 8080 utilizando o script `start` em `package.json`
  yarn start --port 8080
  ```
  </Fragment>
</PackageManagerTabs>

*/}

## `astro dev`

Executa o servidor de desenvolvimento do Astro. Ele é um servidor HTTP local que não faz bundle de assets. Ele utiliza Hot Module Replacement (HMR) para atualizar seu navegador assim que você salva mudanças no seu editor.

<h3>**Flags**</h3>

Utilize essas flags para customizar o comportamento do servidor de desenvolvimento do Astro. Para flags compartilhadas com outros comandos Astro, veja [flags comuns](#flags-comuns) abaixo.

#### `--port`

Especifica em qual porta executar. Por padrão, `4321`.

#### `--host [endereço opcional do host]`

Define em que endereços de IP o servidor de desenvolvimento deve ser escutado em (ou seja, IPs que não sejam localhost). Isso pode ser útil para testar o seu projeto em dispositivos locais como um celular durante o desenvolvimento.

- `--host` - escuta em todos os endereços, incluindo endereços LAN e públicos.
- `--host [endereço-customizado]` - é exposto em um endereço de IP em `[endereço-customizado]`

:::caution
Não utilize a flag `--host` para expor o servidor de desenvolvimento em um ambiente de produção. O servidor de desenvolvimento foi projetado apenas para uso local enquanto desenvolve o seu site.
:::

## `astro build`

Faz a build do seu site para deploy. Por padrão, este comando irá gerar arquivos estáticos que serão colocados no diretório `dist/`. Se [SSR estiver habilitado](/pt-br/guides/server-side-rendering/), o comando irá gerar os arquivos de servidor necessários para servir o seu website.

<h3>Flags</h3>

Utilize essas flags para customizar sua build. Para flags compartilhadas com outros comandos Astro, veja [flags comuns](#flags-comuns) abaixo.

## `astro preview`

Inicia um servidor local para servir seu diretório `dist/` estático.

Este comando é útil para pré-visualizar sua build localmente antes de fazer o deploy. Ele não é feito para ser executado em produção. Para ajuda com hospedagem para produção, veja nosso guia em como [Fazer Deploy de um Website Astro](/pt-br/guides/deploy/).

Desde o Astro 1.5.0, `astro preview` também funciona para builds SSR se você utiliza um adaptador que o suporta. Atualmente, apenas o [adaptador para Node](/pt-br/guides/integrations-guide/node/) suporta `astro preview`.

Pode ser combinado com as [flags comuns](#flags-comuns) documentadas abaixo.

## `astro check`

Roda diagnósticos (como checar a tipagem de arquivos `.astro`) em seu projeto e reporta erros no console. Se algum error for encontrado durante o processo, ele será finalizado com o código **1**.

Esse comando foi feito para ser usado em fluxos de trabalho de CI.

<h3>Flags</h3>

Use estas flags para customizar o comportamento do comando.

#### `--watch`

O comando vai observar qualquer mudança nos arquivos `.astro`, e vai reportar qualquer erro.

:::note
Este comando apenas checa a tipagem em arquivos `.astro`.
:::

📚 Leia mais sobre o [suporte para TypeScript no Astro](/pt-br/guides/typescript/).

## `astro sync`

<p>
  <Since v="2.0.0" />
</p>

:::tip
Executar `astro dev`, `astro build` ou `astro check` irá executar o comando `sync` também.
:::

Gera tipos do TypeScript para todos os módulos do Astro. Ele configura um [arquivo `src/env.d.ts`](/pt-br/guides/typescript/#configuração) para inferência de tipos e define o módulo `astro:content` para a [API de Coleções de Conteúdo](/pt-br/guides/content-collections/).

## `astro add`

Adiciona uma integração a sua configuração. Leia mais no [guia de integrações](/pt-br/guides/integrations-guide/#instalação-automática-de-integrações).

## `astro docs`

Abre o website da documentação do Astro diretamente do seu terminal.

## `astro info`

Reporta informações úteis sobre seu ambiente do Astro atual. Útil para fornecer informações ao abrir uma issue.

```shell
astro info
```

Exemplo de saída:

```
Versão do Astro                 v2.6.6
Gerenciador de pacotes          pnpm
Plataforma                      darwin
Arquitetura                     arm64
Adaptador                       @astrojs/vercel/serverless
Integrações                     Nenhum ou não foi possível determinar.
```

## `astro telemetry`

Define a configuração de telemetria para o usuário da CLI atual. Telemetria são dados anônimos que providenciam informações ao time do Astro sobre quais funcionalidades do Astro são mais utilizadas.

Telemetria pode ser desabilitada com o esse comando de linha de comando:
a
```shell
astro telemetry disable
```

Telemetria pode ser posteriormente habilitada com:

```shell
astro telemetry enable
```

O comando `clear` reseta os dados de telemetria:

```shell
astro telemetry clear
```

:::tip[Gostaria de desabilitar telemetria em ambientes de CI?]
Adicione o comando `astro telemetry disable` em seus scripts de CI ou defina a variável de ambiente `ASTRO_TELEMETRY_DISABLED`.
:::

## Flags Comuns

### `--root <caminho>`

Especifica o caminho para a raiz do projeto. Se não for especificado, o diretório de trabalho atual é assumido como a raiz.

A raiz é utilizada para encontrar o arquivo de configuração Astro.

```shell
astro --root minhaPastaRaiz/minhaPastaDoProjeto dev
```

### `--config <caminho>`

Especifica o caminho para o arquivo de configuração relativo a raiz do projeto. Por padrão, `astro.config.mjs`. Use isso se você utiliza um nome diferente para o seu arquivo de configuração ou se você tem seu arquivo de configuração em outra pasta.

```shell
astro --config config/astro.config.mjs dev
```

### `--site <url>`

Configura a opção [`site`](/pt-br/reference/configuration-reference/#site) para seu projeto. Passar essa flag irá sobrescrever o valor de `site` no seu arquivo `astro.config.mjs`, se um existir.

### `--base <nome-do-caminho>`

<Since v="1.4.1" />

Configura a opção [`base`](/pt-br/reference/configuration-reference/#base) para seu projeto. Passar essa flag irá sobrescrever o valor de `base` no seu arquivo `astro.config.mjs`, se um existir.

### `--verbose`

Habilita logging verboso, que é útil para depurar um problema.

### `--silent`

Habilita logging silencioso, que irá executar o servidor sem nada ser jogado ao terminal.

## Flags Globais

Utilize essas flags para conseguir informação sobre a CLI `astro`.

### `--version`

Mostra o número de versão do Astro.

### `--open`

Automaticamente abre o aplicativo no navegador quando o servidor iniciar.

### `--help`

Mostra a mensagem de ajuda e sai.

## APIs Avançadas (Experimental)

Se você precisa de mais controle ao executar Astro, o pacote `"astro"` também exporta APIs para programaticamente executar os comandos da CLI. 

Essas APIs são experimentais e a assinatura de suas APIs podem mudar. Quaisquer atualizações serão mencionadas no [registro de mudanças do Astro](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) e a informação abaixo irá sempre mostrar a informação atual e atualizada.

### `AstroInlineConfig`

O tipo `AstroInlineConfig` é usado para todas as APIs de comandos abaixo. Ela se estende do tipo da [configuração do Astro](/pt-br/reference/configuration-reference/) do usuário:

```ts
interface AstroInlineConfig extends AstroUserConfig {
	configFile?: string | false;
	mode?: "development" | "production";
	logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}
```

#### `configFile`

<p>

**Tipo:** `string | false`<br />
**Padrão:** `undefined`
</p>

Um caminho customizado para o arquivo de configuração do Astro. 

Se esse valor é undefined (padrão) ou ausente, Astro irá procurar por um arquivo `astro.config.(js,mjs,ts)`relativo ao `root` e irá carregar o arquivo de configuração, se encontrado.

Se um caminho relativo é definido, ele será resolvido com base no diretório de trabalho atual.

Defina para `false` para desabilitar o carregamento de quaisquer arquivos de configuração.

A configuração inline passada nesse objeto irá tomar a maior prioridade ao ser combinada com a configuração do usuário carregada.

#### `mode`

<p>

**Tipo:** `"development" | "production"`<br />
**Padrão:** `"development"` quando executar `astro dev`, `"production"` quando executar `astro build`
</p>

O modo utilizado ao fazer build do seu site para gerar um código de "desenvolvimento" ou "produção".

#### `logLevel`

<p>

**Tipo:** `"debug" | "info" | "warn" | "error" | "silent"`<br />
**Padrão:** `"info"`
</p>

O nível de registro para filtrar mensagens registradas pelo Astro.

- `"debug"`: Registre tudo, incluindo diagnósticos barulhentos de depuração.
- `"info"`: Registre mensagens informacionais, avisos e erros.
- `"warn"`: Registre avisos e erros.
- `"error"`: Registre apenas erros.
- `"silent"`: Sem registros.

### `dev()`

**Tipo:** `(inlineConfig: AstroInlineConfig) => AstroDevServer`

Similar ao [`astro dev`](#astro-dev), ele executa o servidor de desenvolvimento do Astro.

```js
import { dev } from "astro";

const servidorDev = await dev({
  root: "./meu-projeto",
});

// Stop the server if needed
await servidorDev.stop();
```

### `build()`

**Tipo:** `(inlineConfig: AstroInlineConfig) => void`

Similar ao [`astro build`](#astro-build), ele faz build do seu site para deploy.

```js
import { build } from "astro";

await build({
  root: "./meu-projeto",
});
```

### `preview()`

**Tipo:** `(inlineConfig: AstroInlineConfig) => AstroPreviewServer`

Similar ao [`astro preview`](#astro-preview), ele inicia um servidor local para servir seu diretório `dist/` estático.

```js
import { preview } from "astro";

const servidorPreview = await preview({
  root: "./meu-projeto",
});

// Pare o servidor se necessário
await servidorPreview.stop();
```

### `sync()`

**Tipo:** `(inlineConfig: AstroInlineConfig) => number`

Similar ao [`astro sync`](#astro-sync), ele gera tipos do TypeScript para todos os módulos do Astro

```js
import { sync } from "astro";

const codigoSaida = await sync({
  root: "./meu-projeto",
});

process.exit(codigoSaida)
```
